Editing fields are supported by Tools Plus with some notable enhancements over the Macintosh’s standard TextEdit fields. Editing fields (or simply “fields”) are created on the current window by the NewField procedure. Each field is referenced by a unique field number that can be from 1 to 255. This number is specified when the field is created, and refers to the specific field until that field is deleted. Note that the field number is related to its associated window. This means that two different windows can each have a field numbered “1” without interfering with each other. Whenever any field event occurs, such as the user clicking on a field, the PollSystem function reports the field number as well as the window number to which the field belongs.
Field Length Capacity
`````````````````````
Fields are intended to handle small amounts of text, namely 255 characters or less. They are not suitable for handling larger volumes of text. Although an excess of 30,000 characters can exist in a single field (memory permitting), only the first 255 can be retrieved.
Alignment of text in a field
````````````````````````````
Each field can be either left aligned, right aligned, or centered. It cannot, however, be fully justified (i.e. margin to margin). Each field can have its own font, font size, and font styling. Variations of font, size and style within a single field are not possible.
The Active Field
````````````````
Since editing can occur in only one field at a time, the field in which editing occurs is called the active field. Each window can have its own active field, but editing occurs only in the active field on the active window. A field is activated by using the ActivateField procedure. When a field is first activated, an insertion point (called a “caret”) can be placed at the beginning of the field’s text, at the end of the text, or the entire text can be selected. In most cases, the entire text will be selected when the user tabs from one field to the next. When a window becomes inactive, the flashing insertion point disappears and any selected text becomes deselected. When the window is activated again, the insertion point or selection reappears.
A field can be deactivated by either calling the DeactivateField procedure, or by activating another field.
The Field’s String & Edited Text
````````````````````````````````
When a field is first created, a permanent association is made between the field at its text via a handle that points to the field’s string. The field’s string is the text your application provides to a field for editing.
When the field is first activated, a copy of its associated text (the field’s string) is made. It is the copy that is edited within the field while the field’s original string is left untouched. The copy is called the edited text. The edited text can be inspected at any time by calling the GetFieldString procedure, which returns a copy of the edited text. This is necessary to check the field’s edited text for errors prior to accepting it for storage as the field’s string. The edited text can then be saved as the field’s string by calling the SaveFieldString procedure.
When a field is deactivated, the field’s string is re-displayed, thereby replacing the edited text. This is done in case your application deems that the edited text should not be saved as the field’s string. If the edited text was saved as the field’s string, no apparent change will be visible.
Fonts
`````
When a field is first created, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are recorded for the field. The window’s settings can then be changed without affecting the field. Unlike regular Macintosh fields, interacting with these fields does not affect the window’s font settings (font, size, text-transfer mode, and style).
Length Limited Fields
`````````````````````
In some applications, it may be necessary to limit the length of edited text to a specific number of characters. This can be done by calling the FieldLengthLimit procedure with a value of “true.” If a field has been “length limited,” it will not accept any characters that would make the length of the edited text exceed the size of the field’s string. Instead, a beep will be heard when the user types any keys. This also applies when pasting text into a length-limited field.
Word Wrap
`````````
Word wrap automatically occurs in fields. When a word is too long to appear on the current line of a field, the entire word is moved to the next line and scrolling is performed (if necessary) to ensure that the insertion point is visible. A word is defined as any series of characters excluding the space (ASCII character 32) and carriage return (ASCII character 13).
If a field’s height is less than or equal to its font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading ), the field is deemed to be a “single line field.” If a single-line field is either left-aligned or right-aligned, word wrap will not occur. Instead, the field’s text automatically scrolls to ensure that the selection always remains in view.
Clicking and Tabbing in fields
``````````````````````````````
Clicking in an inactive field generates an event that is reported by PollSystem. If a doClickField event is reported, your application would likely call GetFieldString to obtain a copy of the edited text and check the string for errors. If an error is detected, display an appropriate alert box and ignore the doClickField event. If no error is detected, call the SaveFieldString procedure to save the edited text as the field’s string, then call the ClickInField procedure that activates the required field and places the insertion point at the appropriate place.
When a Tab or Shift-Tab key is reported by PollSystem in the form of a doKeyDown or doAutoKey event, your application would likely call the GetFieldString to obtain a copy of the edited text and to check the string for errors. If an error is detected, display an appropriate alert box and ignore the doKeyDown or doAutoKey event. If no error is detected, call the SaveFieldString procedure to save the edited text as the field’s string, then activate the appropriate field by calling ActivateField. If Tab is pressed, activate the next field. If Shift-Tab is pressed, activate the previous field. The PollSystem function details key and mouse events.
Using Fields
````````````
An inactive field cannot be edited by the user. It must first be activated by clicking on the field or tabbing to it. Note, however, that the contents of an inactive field can be changed by your application by using the PasteInField routine.
An active field contains either an insertion point (a flashing caret) or a selection (one or more highlighted characters). A selection of characters is made by extending (dragging the mouse inside a field) away from the insertion point. The insertion point’s position becomes a fixed “anchor,” and the selection is lengthened by moving the “head” away from the anchor, or shortened by moving it towards the anchor. Fields automatically scroll to insure that the selection remains in view.
When a field is active, all key-down and auto-key events are automatically intercepted and processed by the field. Notable exceptions and features are listed below. All events listed below are reported by PollSystem.
Note: Older keyboards, namely those found on the Macintosh 512KE and
Macintosh Plus, have a “Backspace” key instead of a “Delete” key.
However, it performs the same function.
Editing Fields and Typed Characters… What Happens?
When you type characters on the Mac’s keyboard and the an editing field is active, Tools Plus automatically puts those typed characters in the active field (just as you would expect). However, there are some keys on the keyboard which do not produce characters. Instead, the perform some function pertaining to the active field. Below, is a list of those keys and the function they perform:
Command-(key)
`````````````
Any Command-key sequence entered from the keyboard is first interpreted as a menu event. If it matches a menu’s Command-key equivalent, the corresponding menu is highlighted and a doMenu event is generated. Command-key equivalents for Undo, Cut, Copy, and Paste in the Edit menu are processed automatically without generating an event. If the key does not match a menu’s Command-key equivalent, a doKeyDown or doAutoKey event is reported. The edited text and selection are not changed.
Enter
`````
If an enabled default button exists, the Enter key is interpreted as a doButton event for the default button. Otherwise, a doKeyDown or doAutoKey event is reported. The edited text and selection are not changed.
Return
``````
If a window is open that contains an active editing field that accepts the Return key, the field executes a carriage return (move insertion point to the next line). If an enabled default button exists and the active field doesn’t accept the Return key, or a field is not active, the Return key is interpreted as a doButton event for the default button. Otherwise, a doKeyDown or doAutoKey event is reported. The edited text and selection are not changed.
Tab
```
The Tab key generates a doKeyDown or doAutoKey event and must be processed by your application. The edited text and selection are not changed.
Delete
``````
If the Delete key is pressed at an insertion point, the character immediately to the left is erased without being placed on the clipboard. Backspacing on a selection of characters erases the selection.
Delete Forward
``````````````
If the Delete Forward key (available on extended keyboards) is pressed at an insertion point, the character immediately to the right is erased without being placed on the clipboard. Deleting Forward on a selection of characters erases the selection.
Clear
`````
Clear the field (i.e. erase all the characters) without placing them on the clipboard. The clear key and the Clear item in the Edit menu perform the same function.
(Left arrow)
````````````
When used at an insertion point, the caret is moved one character to the left. When used at a selection range, the selection becomes an insertion point at the left side of the selection. The edited text is not changed.
(Shift-left arrow)
``````````````````
Lengthen or shorten the selection by one character (i.e. the range’s head is moved one character to the left). The edited text is not changed.
(Option-left arrow)
```````````````````
Move the insertion point one word to the left. When used at an insertion point, the caret is moved leftward to the beginning of a word. When used at a selection range, the selection becomes an insertion point and moves leftward to the beginning of a word. The edited text is not changed.
(Option-Shift-left arrow)
`````````````````````````
Lengthen or shorten the selection range by one word. When used at an insertion point, a word is selected by moving leftward to the beginning of a word, then the selection is extended by moving the anchor rightward to the end of a single word. When used at a selection range, the selection is first checked to ensure that it starts at the beginning of a word, and ends at the end of a word. If this is the case, the selection range is lengthened or shortened by one word (i.e. the range’s head is moved one word to the left). If the selection does not start at the beginning of a word and/or terminate at the end of a word, a word is selected by moving leftward to the beginning of a word, then the selection is extended by moving the anchor rightward to the end of a single word. In all cases, the edited text is not changed.
(Right-arrow)
`````````````
Move the insertion point one character to the right. When used at an insertion point, the caret is moved one character to the right. When used at a selection range, the selection becomes an insertion point at the right side of the selection. The edited text is not changed.
(Shift-Right-arrow)
```````````````````
Lengthen or shorten the selection by one character (i.e. the range’s head is moved one character to the right). The edited text is not changed.
(Option-Right-arrow)
````````````````````
Move the insertion point one word to the right. When used at an insertion point, the caret is moved rightward to the beginning of a word. When used at a selection range, the selection becomes an insertion point and is moved rightward to the beginning of a word. The edited text is not changed.
(Option-Shift-Right-arrow)
``````````````````````````
Lengthen or shorten the selection range by one word. When used at an insertion point, a word is selected by moving rightward to the beginning of a word, then the selection is extended by moving the anchor leftward to the end of a single word. When used at a selection range, the selection is first checked to ensure that it starts at the beginning of a word, and terminates at the end of a word. If this is the case, the selection range is lengthened or shortened by one word (i.e. the range’s head is moved one word to the right). If the selection does not begin at the beginning of a word and/or terminate at the end of a word, a word is selected by moving rightward to the beginning of a word, then the selection is extended by moving the anchor leftward to the end of a single word. In all cases, the edited text is not changed.
(Up-arrow) or (Option-Up-arrow)
```````````````````````````````
Move the insertion point up one line. When used at an insertion point, the caret is moved up one line. When used at a selection range, the selection becomes an insertion point at the left side of the selection. Nothing happens if the insertion point is on the field’s first line. The edited text is not changed.
(Shift-Up-arrow) or (Option-Shift-Up-arrow)
```````````````````````````````````````````
Lengthen or shorten the selection by one line (i.e. the range’s head is moved up one line). The edited text is not changed.
(Down-arrow) or (Option-Down arrow)
```````````````````````````````````
Move the insertion point down one line. When used at an insertion point, the caret moves down one line. When used at a selection range, the selection becomes an insertion point at the right side of the selection. Nothing happens if the insertion point is on the field’s last line. The edited text is not changed.
(Shift-Down-arrow) or (Option-Shift-Down arrow)
```````````````````````````````````````````````
Lengthen or shorten the selection by one line (i.e. the range’s head is moved down one line). The edited text is not changed.
Clicking or Click/Drag
``````````````````````
Clicking in an active field deselects the current selection and places an insertion point where the mouse was clicked. If the mouse button is held down, the insertion point may be dragged to form a selection range. The field’s text scrolls automatically to keep the selection in view.
If a click occurs in an inactive field, a doClickField event is reported. Your application should then respond by validating the active field’s text (GetFieldString procedure), then saving the field’s edited text by using the SaveFieldString procedure. Then, by calling the ClickInField procedure, the click is processed as previously described.
Double-Clicking or Double Click/Drag
````````````````````````````````````
Double-clicking in an active field deselects the current selection and selects the word that was clicked. If the mouse button is held down, the selection range may be dragged to extend or shorten the range by one word. The field’s text scrolls automatically to keep the selection in view.
If a double-click occurs in an inactive field, a doClickField event is generated. Your application should then respond by validating the active field’s text (GetFieldString procedure), then saving the field’s edited text by using the SaveFieldString procedure. Then, by calling the ClickInField procedure, the double-click is processed as previously described.
Old Macintosh keyboard with numeric pad
```````````````````````````````````````
In order to provide the Shift-Arrow combinations previously described, Tools Plus must discern an Arrow key from a Shift-Arrow key. On the old keyboards, such as those included with the Macintosh 512KE and Macintosh Plus, this causes a slight problem. Shift-(left arrow), for example, produces the same key code as the “+” on the numeric pad. A problem arises when Tools Plus cannot discern between a Shift-(left arrow) and a “+” key on the numeric pad.
It is for this reason that the =, /, *, and + keys on the numeric pad are treated as Shift-(DOWN ARROW), Shift-(up arrow), Shift-(RIGHT ARROW), and Shift-(left arrow) respectively. This occurs only in an active field on a Macintosh 512KE and Macintosh Plus.
The Edit Menu
`````````````
If a second menu exists, it must be called “Edit” and must contain “Undo”, “Cut”, “Copy”, “Paste” and “Clear” as the first five items in the listed order. A dividing line must exist between “Undo” and “Cut”. See the chapter on Menus for more details.
When a field is active in a modeless window, the Edit menu’s “Undo”, “Cut”, “Copy”, “Paste”, and “Clear” items automatically affect the active field in the following manner:
Undo
````
Undo is disabled when a field is activated or deactivated. It is enabled and changed to “Undo Cut” if the Cut command is selected, if a selection range is Deleted, or if a field is Cleared by using the Clear key or Clear menu items. Undo is changed to “Undo Copy” and “Undo Paste” when the respective menus are selected, and changed to “Undo Typing” when keys are typed or the Delete key is used at an insertion point.
Selecting “Undo task” performs all the necessary operations that are required to undo the previous operation, and changes the item to “Redo task.” Selecting “Redo task” restores the field to a state prior to the “Undo task” selection. Undoing and Redoing also remembers insertion point positions and selection ranges.
Cut
```
Cut deletes the selected text from the field and places it on the Clipboard. This item is disabled when a field is deactivated or when an insertion point exists in an active field (i.e. a selection range has not been made).
Copy
````
Copy takes a copy of the selected text and places it on the Clipboard without changing the field. Copy is disabled when a field is deactivated or when an insertion point exists in an active field (i.e. a selection range has not been made).
Paste
`````
At an insertion point, Paste inserts a copy of the Clipboard’s text. At a selection range, Paste replaces the selected characters with the Clipboard’s text. The Clipboard’s contents are not changed.
In a length limited field, the Clipboard’s text is pasted a character at a time (although very quickly) until all the Clipboard’s text has been pasted, or the field is full (whichever comes first).
Paste does not paste Carriage Returns into fields where there are disallowed.
Paste is disabled when a field is deactivated or when no text exists on the Clipboard. Paste is also disabled if a field has been length limited and the insertion point is in a field that has reached its limit of characters (i.e. a full field).
Clear
`````
Clear is disabled when a field is deactivated, or if an active field contains no text (a string length of 0). Clear deletes all the text in the field (i.e. erase all the characters) without placing them on the clipboard. The clear key and the Clear item in the Edit menu perform the same function.
Handling Fields
```````````````
Once a field is activated, Tools Plus performs all the editing required within the field. The PollSystem function, which is used to constantly inquire about any requests the system may have, also processes keystrokes for fields, and maintains the enabled/disabled status for the Edit menu’s Undo, Cut, Copy, Paste, and Clear items.
The active field is automatically affected if the user selects the Edit Menu’s Undo, Cut, Copy, Paste, or Clear command. Command-key equivalents for these items have the same effect.
Many types of events may indicate that the user has completed using the field. For example, a doKeyDown event may report that Tab or Return was pressed, indicating the user wishes to advance to the next field. The doClickField event may indicate that the user has clicked on an inactive field, or the doMenu event may indicate that the user wants to quit your application. In these cases, you will likely want to validate the active field’s edited text before accepting it as the field’s string. A copy of the field’s edited text can be obtained by GetFieldString. If your application determines that the edited text is invalid, display an appropriate alert box and ignore the event. If no error is detected, call the SaveFieldString procedure to save the edited text as the field’s string, then process the event.
See the PollSystem function for details.
Special Handling of Fields
```````````````````````````
Some applications may find it necessary to reposition a field. An example of this occurs in an application that has a matrix of fields aligned as cells: 3 columns across and 10 lines down. If your application needs to “scroll” this block of fields, it is necessary to change the position of existing fields. This can be done by using the OffsetField procedure.
Another unusual circumstance occurs if your application needs to paste text into a field under your application’s control. For example, your application may choose to insert a commonly used word or phrase into a field when the user selects a menu item or a specific command key. The PasteIntoField procedure allows text to be pasted directly into a field.
